CLI Complete Technical Reference

This reference documents the command-line options, environment variables, exit codes, and execution behavior supported by cli.py and the void-builder console script. The complete source checkout is required because the CLI reads configuration, package recipes, hooks, and assets from the repository.

Command Syntax

void-builder [ARCHITECTURE] [OPTIONS]
# or:
python3 cli.py [ARCHITECTURE] [OPTIONS]

Positional Arguments

ARCHITECTURE

  • Description: Target architecture or hardware platform profile.

  • Allowed Values:

    • x86_64 (default)

    • x86_64-musl

    • i686

    • aarch64

    • aarch64-musl

    • armv7l

    • armv7l-musl

    • armv6l

    • armv6l-musl

    • riscv64

    • riscv64-musl

    • rpi-aarch64

    • rpi-armv7l

    • rpi-armv6l

    • pinebookpro

    • asahi

    • x13s

    • rockpro64

    • pine64

    • odroid-c4

    • odroid-n2

    • visionfive2

  • Default: x86_64

--device PROFILE

  • Description: Selects a named hardware profile from configs/hardware/. Profiles can supply a default target architecture, output format, or bootloader; an explicit positional architecture or CLI option takes precedence. Available profiles are asahi, generic-uefi, odroid-c4, odroid-n2, pine64, pinebookpro, rpi4, rockpro64, visionfive2, and x13s.

--platform PROFILE

  • Description: Adds board-specific package and boot metadata to a compatible generic ARM64 or RISC-V target. The built-in profiles with device-tree metadata are asahi, odroid-c4, odroid-n2, pine64, pinebookpro, rockpro64, visionfive2, and x13s. Repeat the option to include more than one platform in a multi-board image.

Presets & Editions

-P PRESET, --preset PRESET

  • Description: Pre-defined unified profile preset from configs/presets/. Configures desktops, package sets, kernel, bootloader, services, and repositories in a single flag.

  • Available Presets:

    • minimal: Minimal console/server system without X11/Wayland.

    • desktop-xfce: Fast and lightweight XFCE workstation with LightDM.

    • desktop-kde: Modern KDE Plasma 6 environment.

    • desktop-gnome: GNOME 4x desktop with GDM.

    • desktop-kde-wayland: KDE Plasma Wayland workstation preset.

    • desktop-gnome-wayland: GNOME Wayland workstation preset.

    • kde-wayland: KDE Plasma Wayland session with Xwayland fallback.

    • gnome-wayland: GNOME Wayland session with Xwayland fallback.

    • xfce-wayland: XFCE Wayland support with Xwayland fallback.

    • rescue-sysadmin: Forensics, disk rescue, partition recovery, and network diagnostic tools (GParted, TestDisk, ddrescue, Wireshark, Nmap).

    • education: Lightweight XFCE classroom edition with a non-administrative installed account and optional age/subject software groups.

    • workplace: Focused XFCE office and business workstation with Firefox, Thunderbird, LibreOffice, PDF, printing/scanning, password management and VPN client support.

    • developer: Comprehensive developer environment (Rust, Go, Python, Podman, Neovim, Zsh, Clang, CMake, Git).

    • gaming: Steam, Vulkan drivers, MangoHud, GameMode, Wine, and automated multilib/nonfree repository enablement.

Performance & Speed Flags

--fast, --quick

  • Description: Selects the builder’s fast-mode settings.

    • Selects the configured fast compression settings, including zstd level 3 where supported. Compression speed and output size depend on the host and image contents.

    • Optimizes SquashFS block size to 256K.

    • Enables fast disk formatting (fast_commit and lazy inode table initialization).

--tmpfs

  • Description: Stages the build work tree in RAM-backed storage. This can reduce disk I/O, requires enough available memory, and does not guarantee a faster build. The mount is cleaned up on completion.

--benchmark

  • Description: Records and prints a structured execution timing report measuring each build stage (Toolchain/Chroot setup, Package installation, Post-install customizations, Bootloader generation, SquashFS compression, and Final artifact generation).

-j JOBS, --jobs JOBS

  • Description: Number of CPU threads to allocate for multi-threaded compression and packaging (default: all available CPU cores).

Execution Modes & Actions

--mode {mock,real}

  • Description: Execution mode.

    • mock: Non-root simulation. Validates configurations, simulates XBPS installation, writes placeholder images.

    • real: Performs actual package downloading, mounting, chroot operations, and binary image creation. Requires root privileges or supported non-root proot execution for the target host and architecture.

  • Default: mock

--dry-run

  • Description: Alias for --mode mock.

--build-calamares

  • Description: Compile the Calamares package from custom_packages/calamares/ and exit.

--with-calamares

  • Description: Recompile Calamares and inject the resulting local repository into the image build.

--build-python-packages

  • Description: Compile all custom Python library packages and exit.

--with-python-packages

  • Description: Compile all custom Python library packages and add the python-libraries profile.

--with-custom-repo

  • Description: Reuse the indexed custom_packages/ repository. This skips Python compilation when matching target-architecture packages are already present and adds the repository to the image build.

--with-kumo

  • Description: Include the Kumo Site-Specific Browser Manager and its runtime dependencies in the image.

--with-xlibre

  • Description: Use the optional XLibre X11 server and drivers on x86_64, x86_64-musl, i686, aarch64, aarch64-musl, armv7l or armv6l-musl. The profile replaces the conflicting X.Org server packages and selects the signed architecture-specific XLibre Void repository. It is not enabled by default.

--with-wayland

  • Description: Include the Wayland protocol libraries, utilities, SwayBG wallpaper helper and Xwayland compatibility profile. It is not enabled by default; choose a Wayland desktop profile such as xfce-wayland, gnome-wayland or kde-wayland to select the session.

-i, --interactive

  • Description: Launches the interactive configuration wizard in the terminal, guiding the user step-by-step through architecture, preset, format, and mode selection.

--check, --validate

  • Description: Runs comprehensive configuration audit (JSON file integrity, profile resolution, package list assembly) and exits without building.

  • Exit Code: 0 on success, 1 on validation failure.

--verify IMAGE_PATH

  • Description: Checks an existing ISO, supported disk image, or rootfs tarball and exits with a verification report. Available structural checks depend on the artifact format and on host inspection tools such as 7z, xorriso, and qemu-img.

  • Architecture check: For rootfs tarballs, the selected ARCHITECTURE is compared with an ELF binary in the archive. ARMv6L and ARMv7L can only be checked as the 32-bit ARM machine family; this verifier does not parse .ARM.attributes to establish the exact ISA level. ARM ELF e_flags encodes ABI version, not ISA level, as specified by the Arm ELF ABI. ISO and disk-image checks do not currently validate the guest architecture.

--verify-platform PLATFORM_NAME

  • Description: Checks that the named hardware profile exists and that its name, optional architecture, command line, DTB path, and package list have valid types and values. The profile values are reported as metadata; they are not proof that the artifact contains that DTB or uses those boot options. Artifact structure is checked separately according to its format.

--clean-cache

  • Description: Clears downloaded XBPS packages and cached stage seed tarballs (cache/xbps, cache/tarballs), then exits.

System & Localization Overrides

--hostname HOSTNAME

  • Description: Overrides system hostname (written to /etc/hostname).

--locale LOCALE

  • Description: Overrides system default locale (e.g. pt_PT.UTF-8, en_US.UTF-8, de_DE.UTF-8). Configures /etc/default/libc-locales and /etc/locale.conf.

--timezone TIMEZONE

  • Description: Overrides system timezone (e.g. Europe/Lisbon, America/Sao_Paulo, UTC). Sets /etc/localtime.

--keymap KEYMAP

  • Description: Overrides console keymap (e.g. pt-latin1, br-abnt2, us). Configures /etc/rc.conf.

Security & User Management

--root-password PASSWORD

  • Description: Sets the root user password directly during system configuration.

--lock-root

  • Description: Disables/locks the root account password for security (passwd -l root).

--live-password PASSWORD

  • Description: Sets a custom password for the live user (default: live).

--ssh-key PATH

  • Description: Path to an SSH public key file to inject into /root/.ssh/authorized_keys and /home/<live_user>/.ssh/authorized_keys with secure permissions (0700/0600). Can be specified multiple times.

--ssh-pubkey "KEY"

  • Description: Direct SSH public key string to append to authorized keys.

Lifecycle Hooks Engine

--hook PHASE:PATH

  • Description: Registers a custom shell hook script to be executed at a specific build stage.

  • Phases:

    • pre-install: Runs before XBPS installs packages.

    • post-install: Runs inside the chroot after package installation and configuration.

    • pre-iso: Runs outside the chroot before SquashFS/disk image compression.

    • post-iso: Runs after output artifacts and checksums are finalized.

  • Example: --hook post-install:configs/hooks/post-install.example.sh

Output & Formats

--format {iso,img,raw,qcow2,vdi,vmdk,vhd,vhdx,tarball,container}

  • Description: Target build artifact format.

    • iso: Hybrid ISO 9660 image with BIOS/UEFI bootloaders for live booting, CDs, DVDs, and flash drives.

    • qcow2: QEMU / KVM Copy-On-Write virtual machine disk image (with built-in compression).

    • vdi: VirtualBox Virtual Disk Image.

    • vmdk: VMware Workstation / ESXi Virtual Machine Disk.

    • vhd / vhdx: Microsoft Hyper-V Virtual Hard Disk formats.

    • img / raw: Partitioned raw disk image (VFAT /boot + EXT4 /) ready for flashing to SD cards, USBs, and eMMC.

    • tarball / container: Compressed .tar.xz or .tar.zst rootfs archive for Docker, Podman, LXC, and other container tools.

  • Default: iso

--compression {xz,zstd,gzip}

  • Description: Compression algorithm for SquashFS container and Dracut initramfs image. Default: xz (or zstd with --fast).

--compress-image, --compress-output, --compress

  • Description: Compresses final raw disk images (.img / .raw) with multi-threaded compression (.img.xz or .img.zst) for smaller download sizes in distribution.

--save-config PATH

  • Description: Exports the assembled build configuration snapshot as JSON to the specified path for documentation and reproducible builds.

--use-tarball [SOURCE], --tarball [SOURCE]

  • Description: Rapidly builds target ISO/image by unpacking a pre-built base system stage seed (.tar.xz / .tar.zst), running xbps-install -Syu inside the chroot, and layering requested desktop/delta package profiles. Real-mode URLs must use HTTPS. Before extraction, real mode requires a matching SHA-256 supplied by --tarball-sha256 or a <tarball>.sha256 sidecar.

--tarball-sha256 SHA256

  • Description: Expected 64-character hexadecimal SHA-256 for the stage seed selected by --use-tarball. Required in real mode if no valid adjacent sidecar exists. The check confirms content integrity against the supplied digest; it does not authenticate its publisher.

--create-tarball

  • Description: Saves the bootstrapped base rootfs as a reusable stage seed tarball with SHA-256, SHA-512, MD5, and manifest sidecars.

--generate-manifest / --no-manifest

  • Description: Enables/disables creation of .sha256, .sha512, .md5, and .manifest.json files alongside the output image. Default: enabled.

--generate-signature / --no-signature

  • Description: Enables/disables per-build GPG signing. The builder creates a temporary signing key, writes a detached signature (.asc) and exports its public key (.gpg-key.asc), then removes the temporary key home. This verifies that the artifact matches the accompanying key; it does not authenticate the publisher. Use a separately trusted signing process when publisher authentication is required.

Exit Codes

  • 0: Successful execution / validation.

  • 1: Build failure, configuration validation error, or permission error.

  • 127: Missing system command dependencies.